PRD: fast_build Reasoner — Speed-Optimized Build Pipeline

Date: 2026-02-18
Status: Final
Scope: Single file — swe_af/app.py only

1. Problem Statement

The existing build() reasoner executes a fully-featured software engineering pipeline that can take 30+ minutes per run. All iteration knobs are set for maximum quality: 2 architect review loops, 5 coding iterations per issue, 2 replans on failure, integration testing, issue advisory, and verify-then-fix cycles. This thoroughness is correct for production shipping but creates excessive latency for rapid prototyping, CI smoke-tests, and developer iteration.

There is no current fast-path entry point. Engineers who need a ~5–10 minute turnaround must manually construct a low-iteration BuildConfig dict and call build() with config=..., which is error-prone and undocumented.

2. Goal

Add a fast_build reasoner to swe_af/app.py that is API-identical to build() but internally overrides BuildConfig with hardcoded fast defaults before delegating to the same pipeline logic. No new files. No new modules. No behavioral divergence from build() beyond configuration.

3. Solution Design

3.1 Refactor: Extract _run_build() helper

Extract the body of build() (lines 64–516) into a private async helper function:

async def _run_build(
    goal: str,
    repo_path: str,
    artifacts_dir: str,
    additional_context: str,
    cfg: BuildConfig,
    execute_fn_target: str,
    max_turns: int,
    permission_mode: str,
    enable_learning: bool,
) -> dict:
    ...  # all existing build() body logic, verbatim

_run_build() is a plain async def — NOT decorated with @app.reasoner(). It is an internal implementation detail.

3.2 Refactor: Rewrite build() as a thin wrapper

build() keeps its exact signature and all behavior. Internally it:

1. Constructs cfg = BuildConfig(**config) if config else BuildConfig()
2. Applies positional-param overrides (repo_url, execute_fn_target, permission_mode, enable_learning, max_turns) — same logic as lines 150–157 of the current implementation
3. Calls await _run_build(goal=goal, repo_path=repo_path, artifacts_dir=artifacts_dir, additional_context=additional_context, cfg=cfg, ...)

3.3 Add fast_build() reasoner

fast_build() is decorated with @app.reasoner() and has the identical parameter signature as build(). Internally it:

1. Defines fast_defaults dict with all 12 overrides (see §4)
2. Merges: merged = {**fast_defaults, **(config or {})} — caller-supplied config wins
3. Constructs cfg = BuildConfig(**merged)
4. Applies positional-param overrides (same 5 checks as build())
5. Calls await _run_build(...) — identical call site to build()

4. Fast Config Defaults — Rationale

5. What Does NOT Change

• build() behavior — no observable changes to the existing reasoner
• Pipeline stages — all 6 stages (plan, git_init, execute, verify, finalize, PR) run in fast_build exactly as in build()
• Return type — fast_build returns BuildResult.model_dump() (same dict schema as build())
• Parameter signatures — fast_build and build() accept identical parameters
• No new files, no new modules, no new schemas
• No new @app.reasoner() handlers beyond fast_build
• plan(), execute(), and resume_build() reasoners — untouched

6. Scope

Must Have

1. _run_build() private async helper extracted from build() body
2. build() refactored as a thin wrapper calling _run_build()
3. fast_build() decorated with @app.reasoner() in swe_af/app.py
4. fast_build() signature identical to build() (same 10 parameters, same defaults)
5. fast_build() constructs BuildConfig from {**fast_defaults, **(config or {})} merge
6. All 12 fast default overrides applied as specified in §4
7. _run_build() is NOT a reasoner (no @app.reasoner() decorator)

Nice to Have

• fast_build listed in the module docstring at top of app.py

Out of Scope

• Changes to any file other than swe_af/app.py
• A fast_plan() standalone reasoner
• Configurable "speed profiles" or named presets
• Changes to BuildConfig defaults
• Changes to plan(), execute(), or resume_build() reasoners
• Performance benchmarking or telemetry for fast vs. normal builds
• Documentation updates beyond docstrings in app.py

7. Assumptions

1. BuildConfig accepts model_config = ConfigDict(extra="forbid") — the fast defaults dict keys must map 1:1 to valid BuildConfig fields. All 12 fields in the fast defaults table exist in the current BuildConfig schema (verified: max_review_iterations, max_retries_per_issue, max_replans, enable_replanning, max_verify_fix_cycles, max_coding_iterations, max_advisor_invocations, enable_issue_advisor, enable_integration_testing, agent_max_turns, agent_timeout_seconds, git_init_max_retries).

2. repo_url is handled by _run_build() via cfg.repo_url — the repo_url positional parameter of build() and fast_build() is applied to cfg.repo_url by the wrapper before calling _run_build(). The helper reads cfg.repo_url directly (as the current build() body does on lines 69–74).

3. _run_build() receives the fully-constructed cfg: BuildConfig object — all positional overrides (repo_url, execute_fn_target, permission_mode, enable_learning, max_turns) are applied by the caller wrapper before passing cfg. The helper does NOT re-apply these.

4. _run_build() does not call app.call(f"{NODE_ID}.build", ...) — it directly runs the pipeline stages inline. It is not a reasoner and cannot be called remotely.

5. Caller-supplied config overrides fast defaults — merge order {**fast_defaults, **(config or {})} means caller wins. Example: fast_build(..., config={"max_coding_iterations": 3}) → max_coding_iterations=3.

6. Module docstring update is nice-to-have — the existing docstring lists build, plan, execute. Adding fast_build to this list is optional and does not affect acceptance criteria.

8. Risks

1. Behavioral regression in build() — Extracting the body into _run_build() is a refactoring risk. Mitigation: The body is moved verbatim. The wrapper applies identical parameter overrides in the same order as the current build() body. Acceptance criteria AC-4 and AC-8 verify no regression.

2. BuildConfig(extra="forbid") validation error — If any fast-default key is misspelled or removed from BuildConfig, BuildConfig(**merged) raises ValidationError at call time. Mitigation: All 12 keys are verified against the current schema (Assumption 1). AC-10 catches import-level issues.

3. _run_build() signature drift — If build() gains new parameters in the future, _run_build() and fast_build() must be updated in sync. Mitigation: Co-location in the same file makes this visible on inspection. No automated guard today.

9. Acceptance Criteria

Each criterion is a concrete, automatable shell command. An agent runs these commands; all must exit 0.

AC-1: fast_build function is registered as a reasoner

python -c "
from swe_af.app import app
names = [r.name for r in app.reasoners]
assert 'fast_build' in names, f'fast_build not found in {names}'
print('PASS: fast_build registered as reasoner')
"

AC-2: fast_build signature is identical to build (same 10 parameters, same defaults)

python -c "
import inspect
from swe_af.app import build, fast_build
build_sig = inspect.signature(build)
fast_sig = inspect.signature(fast_build)
build_params = {k: (v.default, v.annotation) for k, v in build_sig.parameters.items()}
fast_params = {k: (v.default, v.annotation) for k, v in fast_sig.parameters.items()}
assert build_params == fast_params, f'Signatures differ:\nbuild: {build_params}\nfast_build: {fast_params}'
print('PASS: signatures identical')
"

AC-3: _run_build exists, is a coroutine function, and is NOT a registered reasoner

python -c "
import inspect
from swe_af.app import app, _run_build
assert inspect.iscoroutinefunction(_run_build), '_run_build must be async'
names = [r.name for r in app.reasoners]
assert '_run_build' not in names, '_run_build must not be a reasoner'
print('PASS: _run_build exists, is async, is not a reasoner')
"

AC-4: build is still registered as a reasoner (no regression)

python -c "
from swe_af.app import app
names = [r.name for r in app.reasoners]
assert 'build' in names, f'build not found in {names}'
print('PASS: build still registered')
"

AC-5: fast_build source contains all 12 fast default keys and values

python -c "
import inspect
from swe_af import app as app_mod
src = inspect.getsource(app_mod.fast_build)
checks = [
    ('max_review_iterations', '0'),
    ('max_retries_per_issue', '0'),
    ('max_replans', '0'),
    ('enable_replanning', 'False'),
    ('max_verify_fix_cycles', '0'),
    ('max_coding_iterations', '1'),
    ('max_advisor_invocations', '0'),
    ('enable_issue_advisor', 'False'),
    ('enable_integration_testing', 'False'),
    ('agent_max_turns', '50'),
    ('agent_timeout_seconds', '900'),
    ('git_init_max_retries', '1'),
]
for key, val in checks:
    assert key in src, f'Key not found in fast_build source: {key}'
    assert val in src, f'Value {val} not found near {key} in fast_build source'
print('PASS: all 12 fast defaults present in fast_build source')
"

AC-6: fast_build with no config arg passes BuildConfig with all fast defaults to _run_build

python -c "
import asyncio, unittest.mock as mock
captured = {}
async def fake_run_build(goal, repo_path, artifacts_dir, additional_context, cfg, **kwargs):
    captured.update(cfg.model_dump())
    from swe_af.execution.schemas import BuildResult
    return BuildResult(plan_result={}, dag_state={}, verification=None, success=False, summary='', pr_url='').model_dump()
import swe_af.app as mod
with mock.patch.object(mod, '_run_build', fake_run_build):
    asyncio.run(mod.fast_build(goal='test', repo_path='/tmp/fake'))
expects = {
    'max_review_iterations': 0, 'max_retries_per_issue': 0, 'max_replans': 0,
    'enable_replanning': False, 'max_verify_fix_cycles': 0, 'max_coding_iterations': 1,
    'max_advisor_invocations': 0, 'enable_issue_advisor': False,
    'enable_integration_testing': False, 'agent_max_turns': 50,
    'agent_timeout_seconds': 900, 'git_init_max_retries': 1,
}
for k, v in expects.items():
    assert captured[k] == v, f'{k}: expected {v}, got {captured[k]}'
print('PASS: all fast defaults applied to cfg')
"

AC-7: Caller-supplied config overrides fast defaults in fast_build

python -c "
import asyncio, unittest.mock as mock
captured = {}
async def fake_run_build(goal, repo_path, artifacts_dir, additional_context, cfg, **kwargs):
    captured.update(cfg.model_dump())
    from swe_af.execution.schemas import BuildResult
    return BuildResult(plan_result={}, dag_state={}, verification=None, success=False, summary='', pr_url='').model_dump()
import swe_af.app as mod
with mock.patch.object(mod, '_run_build', fake_run_build):
    asyncio.run(mod.fast_build(goal='test', repo_path='/tmp/fake', config={'max_coding_iterations': 3}))
assert captured['max_coding_iterations'] == 3, f'Expected 3 (caller override), got {captured[\"max_coding_iterations\"]}'
assert captured['max_review_iterations'] == 0, 'Other fast defaults must still apply'
print('PASS: caller config overrides fast defaults')
"

AC-8: build() with no config still uses BuildConfig defaults (no regression)

python -c "
import asyncio, unittest.mock as mock
captured = {}
async def fake_run_build(goal, repo_path, artifacts_dir, additional_context, cfg, **kwargs):
    captured.update(cfg.model_dump())
    from swe_af.execution.schemas import BuildResult
    return BuildResult(plan_result={}, dag_state={}, verification=None, success=False, summary='', pr_url='').model_dump()
import swe_af.app as mod
from swe_af.execution.schemas import BuildConfig
with mock.patch.object(mod, '_run_build', fake_run_build):
    asyncio.run(mod.build(goal='test', repo_path='/tmp/fake'))
expected = BuildConfig()
assert captured['max_review_iterations'] == expected.max_review_iterations, \
    f'Expected {expected.max_review_iterations}, got {captured[\"max_review_iterations\"]}'
assert captured['max_coding_iterations'] == expected.max_coding_iterations, \
    f'Expected {expected.max_coding_iterations}, got {captured[\"max_coding_iterations\"]}'
assert captured['agent_max_turns'] == expected.agent_max_turns, \
    f'Expected {expected.agent_max_turns}, got {captured[\"agent_max_turns\"]}'
print('PASS: build() uses BuildConfig defaults unchanged')
"

AC-9: Only swe_af/app.py is modified (no other files changed)

git -C /workspaces/swe-af diff --name-only HEAD | python -c "
import sys
changed = [l.strip() for l in sys.stdin if l.strip()]
non_app = [f for f in changed if f != 'swe_af/app.py']
assert not non_app, f'Unexpected files modified: {non_app}'
print('PASS: only swe_af/app.py modified')
"

AC-10: Module imports cleanly with no syntax or import errors

python -c "import swe_af.app; print('PASS: swe_af.app imports cleanly')"

10. Definition of Done

All 10 acceptance criteria (AC-1 through AC-10) pass when executed as shell commands against the modified swe_af/app.py. No files other than swe_af/app.py are changed.

Architecture: fast_build Reasoner — swe_af/app.py

1. Overview

This document is the single source of truth for the fast_build feature. All
changes are confined to one file: swe_af/app.py. No new files, no new
modules.

The transformation consists of three surgical operations on the existing
build() reasoner:

1. Extract the body of build() into a private async helper _run_build().
2. Rewrite build() as a thin @app.reasoner() wrapper — identical public
   signature, identical runtime behaviour, delegates to _run_build().
3. Add fast_build() as a new @app.reasoner() with the same signature,
   that merges 12 speed-optimised defaults into BuildConfig before delegating
   to _run_build().

2. Module Structure After Change

swe_af/app.py
  ├── _repo_name_from_url()          # unchanged helper
  ├── _run_build()                   # NEW private async helper — NOT a reasoner
  ├── build()                        # @app.reasoner() thin wrapper (refactored)
  ├── fast_build()                   # @app.reasoner() NEW
  ├── plan()                         # @app.reasoner() unchanged
  ├── execute()                      # @app.reasoner() unchanged
  ├── resume_build()                 # @app.reasoner() unchanged
  └── main()                         # unchanged

3. Interfaces (Canonical — Copy Verbatim)

3.1 _run_build (private async helper)

async def _run_build(
    goal: str,
    repo_path: str,
    artifacts_dir: str,
    additional_context: str,
    cfg: "BuildConfig",
    *,
    execute_fn_target: str = "",
    max_turns: int = 0,
    permission_mode: str = "",
    enable_learning: bool = False,
) -> dict:

Responsibility: Contains the entire existing build() body verbatim from
the point after cfg has been constructed and the repo_url override has
been applied — i.e., from the line if execute_fn_target: onwards.

The first lines of _run_build() apply the four positional-parameter overrides
that exist in the current build() body:

if execute_fn_target:
    cfg.execute_fn_target = execute_fn_target
if permission_mode:
    cfg.permission_mode = permission_mode
if enable_learning:
    cfg.enable_learning = True
if max_turns > 0:
    cfg.agent_max_turns = max_turns

Then the full existing pipeline body follows unchanged.

Returns: BuildResult(...).model_dump() — exactly as the current build()
does today.

Error cases (unchanged from today):

• ValueError("Either repo_path or repo_url must be provided") — raised when
  neither repo_path nor cfg.repo_url is set.
• RuntimeError(f"git clone failed (exit {code}): {err}") — raised when
  subprocess.run(["git", "clone", ...]) exits non-zero.
• RuntimeError(f"git re-clone failed: {err}") — raised when re-clone after
  failed reset exits non-zero.

NOT decorated with @app.reasoner().

3.2 build (refactored thin wrapper)

@app.reasoner()
async def build(
    goal: str,
    repo_path: str = "",
    repo_url: str = "",
    artifacts_dir: str = ".artifacts",
    additional_context: str = "",
    config: dict | None = None,
    execute_fn_target: str = "",
    max_turns: int = 0,
    permission_mode: str = "",
    enable_learning: bool = False,
) -> dict:
    """End-to-end: plan → execute → verify → optional fix cycle.

    This is the single entry point. Pass a goal, get working code.

    If ``repo_url`` is provided and ``repo_path`` is empty, the repo is cloned
    into ``/workspaces/<repo-name>`` automatically (useful in Docker).
    """
    from swe_af.execution.schemas import BuildConfig
    cfg = BuildConfig(**config) if config else BuildConfig()
    if repo_url:
        cfg.repo_url = repo_url
    return await _run_build(
        goal=goal,
        repo_path=repo_path,
        artifacts_dir=artifacts_dir,
        additional_context=additional_context,
        cfg=cfg,
        execute_fn_target=execute_fn_target,
        max_turns=max_turns,
        permission_mode=permission_mode,
        enable_learning=enable_learning,
    )

Behavioural contract: Runtime-observable behaviour is identical to the
current implementation. BuildConfig is constructed with exactly the same
logic; the repo_url override is applied before passing cfg to _run_build.

3.3 fast_build (new reasoner)

@app.reasoner()
async def fast_build(
    goal: str,
    repo_path: str = "",
    repo_url: str = "",
    artifacts_dir: str = ".artifacts",
    additional_context: str = "",
    config: dict | None = None,
    execute_fn_target: str = "",
    max_turns: int = 0,
    permission_mode: str = "",
    enable_learning: bool = False,
) -> dict:
    """Speed-optimised build: identical API to build() with fast defaults.

    Hardcodes a minimal BuildConfig before delegating to the same pipeline.
    Caller-supplied ``config`` keys override fast defaults on a per-key basis.
    """
    from swe_af.execution.schemas import BuildConfig

    fast_defaults: dict = {
        "max_review_iterations":      0,
        "max_retries_per_issue":      0,
        "max_replans":                0,
        "enable_replanning":          False,
        "max_verify_fix_cycles":      0,
        "max_coding_iterations":      1,
        "max_advisor_invocations":    0,
        "enable_issue_advisor":       False,
        "enable_integration_testing": False,
        "agent_max_turns":            50,
        "agent_timeout_seconds":      900,
        "git_init_max_retries":       1,
    }
    merged = {**fast_defaults, **(config or {})}
    cfg = BuildConfig(**merged)
    if repo_url:
        cfg.repo_url = repo_url
    return await _run_build(
        goal=goal,
        repo_path=repo_path,
        artifacts_dir=artifacts_dir,
        additional_context=additional_context,
        cfg=cfg,
        execute_fn_target=execute_fn_target,
        max_turns=max_turns,
        permission_mode=permission_mode,
        enable_learning=enable_learning,
    )

Key semantic: {**fast_defaults, **(config or {})} — caller's config
values override fast defaults on a key-by-key basis. Any key absent from
caller's config takes the fast default value.

4. Data Flow

4.1 build() call path

build(goal, repo_path, ..., config=None)
  │
  ├─ BuildConfig(**config) or BuildConfig()        # cfg constructed
  ├─ if repo_url: cfg.repo_url = repo_url          # repo_url override
  │
  └─ _run_build(goal, repo_path, ..., cfg)
       ├─ if execute_fn_target: cfg.execute_fn_target = ...
       ├─ if permission_mode:   cfg.permission_mode   = ...
       ├─ if enable_learning:   cfg.enable_learning   = True
       ├─ if max_turns > 0:     cfg.agent_max_turns   = max_turns
       │
       ├─ Phase 1: plan() + git_init (concurrent)
       ├─ Phase 2: execute()
       ├─ Phase 3: verify() [+ optional fix cycles]
       ├─ Phase 3b: run_repo_finalize()
       ├─ Phase 4: run_github_pr() (if remote present)
       └─ return BuildResult(...).model_dump()

4.2 fast_build() call path

fast_build(goal, repo_path, ..., config=None)
  │
  ├─ fast_defaults = {max_review_iterations:0, ..., git_init_max_retries:1}
  ├─ merged = {**fast_defaults, **(config or {})}  # caller overrides defaults
  ├─ BuildConfig(**merged)                          # cfg constructed
  ├─ if repo_url: cfg.repo_url = repo_url          # repo_url override
  │
  └─ _run_build(goal, repo_path, ..., cfg)
       └─ (identical pipeline to build() above)

4.3 Concrete fast_defaults effect on pipeline

5. Error Handling

All error handling is inherited unchanged from the existing build() body
that becomes _run_build(). No new error types are introduced.

6. Architectural Decisions

Decision 1: _run_build accepts cfg: BuildConfig (already-constructed)

Chosen: _run_build takes the fully-constructed BuildConfig object.

Rejected: Passing config: dict | None into _run_build and constructing
BuildConfig inside it.

Rationale: Both build() and fast_build() need distinct BuildConfig
construction logic (plain defaults vs. merged fast defaults). Keeping
construction in the wrapper avoids conditional logic inside _run_build and
keeps the helper's signature stable regardless of future wrappers.

Decision 2: fast_defaults dict defined inline in fast_build() body

Chosen: A local fast_defaults dict literal inside fast_build().

Rejected: A module-level constant; a class attribute; a helper function.

Rationale: Acceptance criterion 5 verifies the values by inspecting
inspect.getsource(fast_build). A module-level FAST_DEFAULTS constant would
NOT appear in fast_build's source — only the constant name would. The local
dict literal is the only form that guarantees all 12 key-value pairs are
verifiable in fast_build's own source text.

Decision 3: Merge order {**fast_defaults, **(config or {})}

Chosen: Fast defaults are the base; caller config overrides.

Rejected: Caller config as the base; fast defaults clobber caller.

Rationale: Semantics are "speed-optimised by default, opt into slower
behaviour per key." Callers who pass config={'max_coding_iterations': 3}
expect that override to take effect. Caller values always win.

Decision 4: repo_url override applied in wrapper, not _run_build

Chosen: Both build() and fast_build() set cfg.repo_url = repo_url
before calling _run_build().

Rationale: repo_url modifies cfg and belongs in the
configuration-construction phase alongside BuildConfig(...). _run_build()
should receive a fully configured cfg; it does not accept repo_url as a
parameter.

Decision 5: Four positional-parameter overrides live in _run_build()

Chosen: The four overrides below remain at the top of _run_build():

if execute_fn_target: cfg.execute_fn_target = execute_fn_target
if permission_mode:   cfg.permission_mode   = permission_mode
if enable_learning:   cfg.enable_learning   = True
if max_turns > 0:     cfg.agent_max_turns   = max_turns

_run_build() accepts execute_fn_target, max_turns, permission_mode,
enable_learning as keyword-only arguments.

Rejected: Duplicating these guards in each wrapper.

Rationale: Both build() and fast_build() need them. Centralising in
_run_build() eliminates duplication and ensures future wrappers get them for
free.

7. File Change Summary

Only swe_af/app.py is modified.

No new imports at module level — BuildConfig and BuildResult continue to
be imported inside the function body via from swe_af.execution.schemas import BuildConfig, BuildResult (the import moves into _run_build() body, and each
wrapper imports only BuildConfig).

8. Verification Checklist Against Acceptance Criteria